home *** CD-ROM | disk | FTP | other *** search
/ Apple Developer Connection Student Program / ADC Tools Sampler CD Disk 3 1999.iso / Metrowerks CodeWarrior / Java Support / Java_Source / Java2 / src / java / io / InputStream.java < prev    next >
Encoding:
Java Source  |  1999-05-28  |  14.5 KB  |  354 lines  |  [TEXT/CWIE]
  1. /*
  2.  * @(#)InputStream.java    1.34 98/08/16
  3.  *
  4.  * Copyright 1994-1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.io;
  16.  
  17. /**
  18.  * This abstract class is the superclass of all classes representing
  19.  * an input stream of bytes.
  20.  *
  21.  * <p> Applications that need to define a subclass of <code>InputStream</code>
  22.  * must always provide a method that returns the next byte of input.
  23.  *
  24.  * @author  Arthur van Hoff
  25.  * @version 1.34, 08/16/98
  26.  * @see     java.io.BufferedInputStream
  27.  * @see     java.io.ByteArrayInputStream
  28.  * @see     java.io.DataInputStream
  29.  * @see     java.io.FilterInputStream
  30.  * @see     java.io.InputStream#read()
  31.  * @see     java.io.OutputStream
  32.  * @see     java.io.PushbackInputStream
  33.  * @since   JDK1.0
  34.  */
  35. public abstract class InputStream {
  36.  
  37.     // SKIP_BUFFER_SIZE is used to determine the size of skipBuffer
  38.     private static final int SKIP_BUFFER_SIZE = 2048;
  39.     // skipBuffer is initialized in skip(long), if needed.
  40.     private static byte[] skipBuffer;
  41.  
  42.     /**
  43.      * Reads the next byte of data from the input stream. The value byte is
  44.      * returned as an <code>int</code> in the range <code>0</code> to
  45.      * <code>255</code>. If no byte is available because the end of the stream
  46.      * has been reached, the value <code>-1</code> is returned. This method
  47.      * blocks until input data is available, the end of the stream is detected,
  48.      * or an exception is thrown.
  49.      *
  50.      * <p> A subclass must provide an implementation of this method.
  51.      *
  52.      * @return     the next byte of data, or <code>-1</code> if the end of the
  53.      *             stream is reached.
  54.      * @exception  IOException  if an I/O error occurs.
  55.      */
  56.     public abstract int read() throws IOException;
  57.  
  58.     /**
  59.      * Reads some number of bytes from the input stream and stores them into
  60.      * the buffer array <code>b</code>. The number of bytes actually read is
  61.      * returned as an integer.  This method blocks until input data is
  62.      * available, end of file is detected, or an exception is thrown.
  63.      *
  64.      * <p> If <code>b</code> is <code>null</code>, a
  65.      * <code>NullPointerException</code> is thrown.  If the length of
  66.      * <code>b</code> is zero, then no bytes are read and <code>0</code> is
  67.      * returned; otherwise, there is an attempt to read at least one byte. If
  68.      * no byte is available because the stream is at end of file, the value
  69.      * <code>-1</code> is returned; otherwise, at least one byte is read and
  70.      * stored into <code>b</code>.
  71.      *
  72.      * <p> The first byte read is stored into element <code>b[0]</code>, the
  73.      * next one into <code>b[1]</code>, and so on. The number of bytes read is,
  74.      * at most, equal to the length of <code>b</code>. Let <i>k</i> be the
  75.      * number of bytes actually read; these bytes will be stored in elements
  76.      * <code>b[0]</code> through <code>b[</code><i>k</i><code>-1]</code>,
  77.      * leaving elements <code>b[</code><i>k</i><code>]</code> through
  78.      * <code>b[b.length-1]</code> unaffected.
  79.      *
  80.      * <p> If the first byte cannot be read for any reason other than end of
  81.      * file, then an <code>IOException</code> is thrown. In particular, an
  82.      * <code>IOException</code> is thrown if the input stream has been closed.
  83.      *
  84.      * <p> The <code>read(b)</code> method for class <code>InputStream</code>
  85.      * has the same effect as: <pre><code> read(b, 0, b.length) </code></pre>
  86.      *
  87.      * @param      b   the buffer into which the data is read.
  88.      * @return     the total number of bytes read into the buffer, or
  89.      *             <code>-1</code> is there is no more data because the end of
  90.      *             the stream has been reached.
  91.      * @exception  IOException  if an I/O error occurs.
  92.      * @see        java.io.InputStream#read(byte[], int, int)
  93.      */
  94.     public int read(byte b[]) throws IOException {
  95.     return read(b, 0, b.length);
  96.     }
  97.  
  98.     /**
  99.      * Reads up to <code>len</code> bytes of data from the input stream into
  100.      * an array of bytes.  An attempt is made to read as many as
  101.      * <code>len</code> bytes, but a smaller number may be read, possibly
  102.      * zero. The number of bytes actually read is returned as an integer.
  103.      *
  104.      * <p> This method blocks until input data is available, end of file is
  105.      * detected, or an exception is thrown.
  106.      *
  107.      * <p> If <code>b</code> is <code>null</code>, a
  108.      * <code>NullPointerException</code> is thrown.
  109.      *
  110.      * <p> If <code>off</code> is negative, or <code>len</code> is negative, or
  111.      * <code>off+len</code> is greater than the length of the array
  112.      * <code>b</code>, then an <code>IndexOutOfBoundsException</code> is
  113.      * thrown.
  114.      *
  115.      * <p> If <code>len</code> is zero, then no bytes are read and
  116.      * <code>0</code> is returned; otherwise, there is an attempt to read at
  117.      * least one byte. If no byte is available because the stream is at end of
  118.      * file, the value <code>-1</code> is returned; otherwise, at least one
  119.      * byte is read and stored into <code>b</code>.
  120.      *
  121.      * <p> The first byte read is stored into element <code>b[off]</code>, the
  122.      * next one into <code>b[off+1]</code>, and so on. The number of bytes read
  123.      * is, at most, equal to <code>len</code>. Let <i>k</i> be the number of
  124.      * bytes actually read; these bytes will be stored in elements
  125.      * <code>b[off]</code> through <code>b[off+</code><i>k</i><code>-1]</code>,
  126.      * leaving elements <code>b[off+</code><i>k</i><code>]</code> through
  127.      * <code>b[off+len-1]</code> unaffected.
  128.      *
  129.      * <p> In every case, elements <code>b[0]</code> through
  130.      * <code>b[off]</code> and elements <code>b[off+len]</code> through
  131.      * <code>b[b.length-1]</code> are unaffected.
  132.      *
  133.      * <p> If the first byte cannot be read for any reason other than end of
  134.      * file, then an <code>IOException</code> is thrown. In particular, an
  135.      * <code>IOException</code> is thrown if the input stream has been closed.
  136.      *
  137.      * <p> The <code>read(b,</code> <code>off,</code> <code>len)</code> method
  138.      * for class <code>InputStream</code> simply calls the method
  139.      * <code>read()</code> repeatedly. If the first such call results in an
  140.      * <code>IOException</code>, that exception is returned from the call to
  141.      * the <code>read(b,</code> <code>off,</code> <code>len)</code> method.  If
  142.      * any subsequent call to <code>read()</code> results in a
  143.      * <code>IOException</code>, the exception is caught and treated as if it
  144.      * were end of file; the bytes read up to that point are stored into
  145.      * <code>b</code> and the number of bytes read before the exception
  146.      * occurred is returned.  Subclasses are encouraged to provide a more
  147.      * efficient implementation of this method.
  148.      *
  149.      * @param      b     the buffer into which the data is read.
  150.      * @param      off   the start offset in array <code>b</code>
  151.      *                   at which the data is written.
  152.      * @param      len   the maximum number of bytes to read.
  153.      * @return     the total number of bytes read into the buffer, or
  154.      *             <code>-1</code> if there is no more data because the end of
  155.      *             the stream has been reached.
  156.      * @exception  IOException  if an I/O error occurs.
  157.      * @see        java.io.InputStream#read()
  158.      */
  159.     public int read(byte b[], int off, int len) throws IOException {
  160.     if (b == null) {
  161.         throw new NullPointerException();
  162.     } else if ((off < 0) || (off > b.length) || (len < 0) ||
  163.            ((off + len) > b.length) || ((off + len) < 0)) {
  164.         throw new IndexOutOfBoundsException();
  165.     } else if (len == 0) {
  166.         return 0;
  167.     }
  168.  
  169.     int c = read();
  170.     if (c == -1) {
  171.         return -1;
  172.     }
  173.     b[off] = (byte)c;
  174.  
  175.     int i = 1;
  176.     try {
  177.         for (; i < len ; i++) {
  178.         c = read();
  179.         if (c == -1) {
  180.             break;
  181.         }
  182.         if (b != null) {
  183.             b[off + i] = (byte)c;
  184.         }
  185.         }
  186.     } catch (IOException ee) {
  187.     }
  188.     return i;
  189.     }
  190.  
  191.     /**
  192.      * Skips over and discards <code>n</code> bytes of data from this input
  193.      * stream. The <code>skip</code> method may, for a variety of reasons, end
  194.      * up skipping over some smaller number of bytes, possibly <code>0</code>.
  195.      * This may result from any of a number of conditions; reaching end of file
  196.      * before <code>n</code> bytes have been skipped is only one possibility.
  197.      * The actual number of bytes skipped is returned.  If <code>n</code> is
  198.      * negative, no bytes are skipped.
  199.      *
  200.      * <p> The <code>skip</code> method of <code>InputStream</code> creates a
  201.      * byte array and then repeatedly reads into it until <code>n</code> bytes
  202.      * have been read or the end of the stream has been reached. Subclasses are
  203.      * encouraged to provide a more efficient implementation of this method.
  204.      *
  205.      * @param      n   the number of bytes to be skipped.
  206.      * @return     the actual number of bytes skipped.
  207.      * @exception  IOException  if an I/O error occurs.
  208.      */
  209.     public long skip(long n) throws IOException {
  210.  
  211.     long remaining = n;
  212.     int nr;
  213.     if (skipBuffer == null)
  214.         skipBuffer = new byte[SKIP_BUFFER_SIZE];
  215.  
  216.     byte[] localSkipBuffer = skipBuffer;
  217.         
  218.     if (n <= 0) {
  219.         return 0;
  220.     }
  221.  
  222.     while (remaining > 0) {
  223.         nr = read(localSkipBuffer, 0,
  224.               (int) Math.min(SKIP_BUFFER_SIZE, remaining));
  225.         if (nr < 0) {
  226.         break;
  227.         }
  228.         remaining -= nr;
  229.     }
  230.     
  231.     return n - remaining;
  232.     }
  233.  
  234.     /**
  235.      * Returns the number of bytes that can be read (or skipped over) from
  236.      * this input stream without blocking by the next caller of a method for
  237.      * this input stream.  The next caller might be the same thread or or
  238.      * another thread.
  239.      *
  240.      * <p> The <code>available</code> method for class <code>InputStream</code>
  241.      * always returns <code>0</code>.
  242.      *
  243.      * <p> This method should be overridden by subclasses.
  244.      *
  245.      * @return     the number of bytes that can be read from this input stream
  246.      *             without blocking.
  247.      * @exception  IOException  if an I/O error occurs.
  248.      */
  249.     public int available() throws IOException {
  250.     return 0;
  251.     }
  252.  
  253.     /**
  254.      * Closes this input stream and releases any system resources associated
  255.      * with the stream.
  256.      *
  257.      * <p> The <code>close</code> method of <code>InputStream</code> does
  258.      * nothing.
  259.      *
  260.      * @exception  IOException  if an I/O error occurs.
  261.      */
  262.     public void close() throws IOException {}
  263.  
  264.     /**
  265.      * Marks the current position in this input stream. A subsequent call to
  266.      * the <code>reset</code> method repositions this stream at the last marked
  267.      * position so that subsequent reads re-read the same bytes.
  268.      *
  269.      * <p> The <code>readlimit</code> arguments tells this input stream to
  270.      * allow that many bytes to be read before the mark position gets
  271.      * invalidated.
  272.      *
  273.      * <p> The general contract of <code>mark</code> is that, if the method
  274.      * <code>markSupported</code> returns <code>true</code>, the stream somehow
  275.      * remembers all the bytes read after the call to <code>mark</code> and
  276.      * stands ready to supply those same bytes again if and whenever the method
  277.      * <code>reset</code> is called.  However, the stream is not required to
  278.      * remember any data at all if more than <code>readlimit</code> bytes are
  279.      * read from the stream before <code>reset</code> is called.
  280.      *
  281.      * <p> The <code>mark</code> method of <code>InputStream</code> does
  282.      * nothing.
  283.      *
  284.      * @param   readlimit   the maximum limit of bytes that can be read before
  285.      *                      the mark position becomes invalid.
  286.      * @see     java.io.InputStream#reset()
  287.      */
  288.     public synchronized void mark(int readlimit) {}
  289.  
  290.     /**
  291.      * Repositions this stream to the position at the time the
  292.      * <code>mark</code> method was last called on this input stream.
  293.      *
  294.      * <p> The general contract of <code>reset</code> is:
  295.      *
  296.      * <p><ul>
  297.      *
  298.      * <li> If the method <code>markSupported</code> returns
  299.      * <code>true</code>, then:
  300.      *
  301.      *     <ul><li> If the method <code>mark</code> has not been called since
  302.      *     the stream was created, or the number of bytes read from the stream
  303.      *     since <code>mark</code> was last called is larger than the argument
  304.      *     to <code>mark</code> at that last call, then an
  305.      *     <code>IOException</code> might be thrown.
  306.      *
  307.      *     <li> If such an <code>IOException</code> is not thrown, then the
  308.      *     stream is reset to a state such that all the bytes read since the
  309.      *     most recent call to <code>mark</code> (or since the start of the
  310.      *     file, if <code>mark</code> has not been called) will be resupplied
  311.      *     to subsequent callers of the <code>read</code> method, followed by
  312.      *     any bytes that otherwise would have been the next input data as of
  313.      *     the time of the call to <code>reset</code>. </ul>
  314.      *
  315.      * <li> If the method <code>markSupported</code> returns
  316.      * <code>false</code>, then:
  317.      *
  318.      *     <ul><li> The call to <code>reset</code> may throw an
  319.      *     <code>IOException</code>.
  320.      *
  321.      *     <li> If an <code>IOException</code> is not thrown, then the stream
  322.      *     is reset to a fixed state that depends on the particular type of the
  323.      *     input stream and how it was created. The bytes that will be supplied
  324.      *     to subsequent callers of the <code>read</code> method depend on the
  325.      *     particular type of the input stream. </ul></ul>
  326.      *
  327.      * <p> The method <code>reset</code> for class <code>InputStream</code>
  328.      * does nothing and always throws an <code>IOException</code>.
  329.      *
  330.      * @exception  IOException  if this stream has not been marked or if the
  331.      *               mark has been invalidated.
  332.      * @see     java.io.InputStream#mark(int)
  333.      * @see     java.io.IOException
  334.      */
  335.     public synchronized void reset() throws IOException {
  336.     throw new IOException("mark/reset not supported");
  337.     }
  338.  
  339.     /**
  340.      * Tests if this input stream supports the <code>mark</code> and
  341.      * <code>reset</code> methods. The <code>markSupported</code> method of
  342.      * <code>InputStream</code> returns <code>false</code>.
  343.      *
  344.      * @return  <code>true</code> if this true type supports the mark and reset
  345.      *          method; <code>false</code> otherwise.
  346.      * @see     java.io.InputStream#mark(int)
  347.      * @see     java.io.InputStream#reset()
  348.      */
  349.     public boolean markSupported() {
  350.     return false;
  351.     }
  352.  
  353. }
  354.